Inside Macintosh: QuickTime Components

Previous | Chapter Top | Chapter Contents | Next

Working With Channel Devices

Sequence grabbers provide a number of functions that allow you to determine the device that is attached to a given sequence grabber channel. These devices allow the channel component to control the digitizing equipment. For example, video channels use video digitizer components, and sound channels use sound input drivers. Your application can use these routines to present a list of available devices to the user, allowing the user to select a specific device for each channel.

You may use the SGGetChannelDeviceList function to retrieve a list of devices that may be used with a specified channel. You dispose of this device list by calling the SGDisposeDeviceList function. You can place one or more device names into a menu by calling the SGAppendDeviceListToMenu function. You can use the SGSetChannelDevice function to assign a device to a channel.

Some of these functions use a device list structure to pass information about one or more channel devices. The SGDeviceListRecord data type defines the format of the device list structure.

typedef struct SGDeviceListRecord {
    short               count;                  /* count of devices */
    short               selectedIndex;          /* current device */
    long                reserved;               /* set to 0 */
    SGDeviceName        entry[1];               /* device names */
} SGDeviceListRecord, *SGDeviceListPtr, **SGDeviceList;
count
Indicates the number of devices described by this structure. The value of this field corresponds to the number of entries in the device name array defined by the entry field.
selectedIndex
Identifies the currently active device. The value of this field corresponds to the appropriate entry in the device name array defined by the entry field. Note that this value is 0-relative; that is, the first entry has an index number of 0, the second's value is 1, and so on.
reserved
Reserved for Apple. Always set to 0.
entry
Contains an array of device name structures. Each structure corresponds to one valid device. The count field indicates the number of entries in this array. The SGDeviceName data type defines the format of a device name structure; this data type is discussed next.

Device list structures contain an array of device name structures. Each device name structure identifies a single device that may be used by the channel. The SGDeviceName data type defines the format of a device name structure.

typedef struct SGDeviceName {
    Str63           name;                   /* device name */
    Handle          icon;                   /* device icon */
    long            flags;                  /* flags */
    long            refCon;                 /* set to 0 */
    long            reserved;               /* set to 0 */
} SGDeviceName;

Field descriptions

name
Contains the name of the device. For video digitizer components, this field contains the component's name as specified in the component resource. For sound input drivers, this field contains the driver name.
icon
Contains a handle to the device's icon. Some devices may support an icon, which you may choose to present to the user. If the device does not support an icon, or if you choose not to retrieve this information (by setting the sgDeviceListWithIcons flag to 0 when you call the SGGetChannelDeviceList function), this field is set to nil .
flags
Reflects the current status of the device. The sequence grabber sets these flags when you retrieve a device list. The following flag is defined:
sgDeviceNameFlagDeviceUnavailable
When set to 1, this flag indicates that this device is not currently available.
refCon
Reserved for Apple. Always set to 0.
reserved
Reserved for Apple. Always set to 0.

SGGetChannelDeviceList

The SGGetChannelDeviceList function allows you to retrieve a list of the devices that are valid for a specified channel.

pascal ComponentResult SGGetChannelDeviceList (SGChannel c,
                                         long selectionFlags,
                                         SGDeviceList *list);
c
Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the SGNewChannel or SGNewChannelFromComponent function, discussed on SGNewChannel and SGNewChannelFromComponent , respectively.
selectionFlags
Controls the data returned for each device. The following flags are defined:
sgDeviceListWithIcons
Specifies whether you want to retrieve an icon for each device. If you set this flag to 1, the sequence grabber returns an icon for each device in the list, in the icon field. If you set this flag to 0, the sequence grabber sets the icon fields to 0.
sgDeviceListDontCheckAvailability
Controls whether the sequence grabber verifies that each device is currently available. If you set this flag to 1, the sequence grabber does not check the availability of each device. Otherwise, the sequence grabber checks each device's availability, and sets the sgDeviceNameFlagDeviceUnavailable flag appropriately in each device name structure that is returned.
Note that checking device availability slows this function. In general, however, you should check availability if you plan to present a list of devices to the user. Otherwise, the user may select a device that is unavailable.
list
Defines a pointer to a device list structure pointer. The sequence grabber creates a device name structure and returns a pointer to that structure in the field referred to by this parameter. When you are done with the list, use the SGDisposeDeviceList function (described in the next section) to dispose of the memory used by the list.

DESCRIPTION

This function allows you to retrieve a list of the devices that may be used with a channel. Each entry in this list identifies a valid device by name. Your application may then place these device names into a menu using the SGAppendDeviceListToMenu function, which is described on SGAppendDeviceListToMenu .

This function can be useful for retrieving the name of the current device. Retrieve the device list and use the selectedIndex field to determine which device is currently in use.

RESULT CODES

Memory Manager errors

SEE ALSO

When you are done with the list, use the SGDisposeDeviceList function to dispose of the memory used by the list. This function is discussed next.

SGDisposeDeviceList

The SGDisposeDeviceList function allows you to dispose of a device list.

pascal ComponentResult SGDisposeDeviceList (SeqGrabComponent s,
                                          SGDeviceList list);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
list
Defines a pointer to a device list structure pointer. The sequence grabber disposes of the memory used by the device list structure.

DESCRIPTION

You must use this function to dispose of the memory used by a device list structure. Do not use Memory Manager functions to do so.

RESULT CODES

Memory Manager errors

SGAppendDeviceListToMenu

The SGAppendDeviceListToMenu function allows you to place a list of device names into a specified menu.

pascal ComponentResult SGAppendDeviceListToMenu
                                         (SeqGrabComponent s,
                                         SGDeviceList list, MenuHandle mh);
s
Specifies the component instance that identifies your connection to the sequence grabber component. You obtain this value from the Component Manager's OpenDefaultComponent or OpenComponent function.
list
Defines a pointer to a device list structure pointer. The sequence grabber appends the name of each device in the list to the menu specified by the mh parameter. If the sgDeviceNameFlagDeviceUnavailable flag is set to 1 for a device in the list, the sequence grabber disables the menu item corresponding to that device.
mh
Specifies the menu to which the device names are to be appended.

DESCRIPTION

You may use the SGAppendDeviceListToMenu function to present a list of valid devices to the user. The user may then select a device from the list. You can assign that device to a channel by calling the SGSetChannelDevice function. Note that, if you choose to have the sequence grabber check the availability of each device (by setting the sgDeviceListDontCheckAvailability flag to 0 with the SGGetChannelDeviceList function), the sequence grabber will disable menu items that correspond to unavailable devices. This prevents the user from selecting a device that cannot be used.

RESULT CODE

paramErr

-50

Invalid parameter value

SEE ALSO

You obtain the device list by calling the SGGetChannelDeviceList function, which is discussed on SGGetChannelDeviceList .

SGSetChannelDevice

The SGSetChannelDevice function allows you to assign a device to a channel.

pascal ComponentResult SGSetChannelDevice (SGChannel c,
                                         StringPtr name);
c
Identifies the channel for this operation. You provide your connection identifier. You connect to a channel component by calling the SGNewChannel or SGNewChannelFromComponent function, discussed on SGNewChannel and SGNewChannelFromComponent , respectively.
name
Points to the device's name string. This name is contained in the name field of the appropriate device name structure in the device list.

DESCRIPTION

When you call the SGSetChannelDevice function, the sequence grabber channel tries to use the specified device, in place of the device currently in use. You must obtain the device name from the channel's device list.

RESULT CODES

paramErr

-50

Invalid parameter value

deviceCantMeetRequest

-9408

Device cannot support grabber

SEE ALSO

You obtain the device list by calling the SGGetChannelDeviceList function, which is described on SGGetChannelDeviceList .

© 1997 Apple Computer, Inc.

Previous | Chapter Top | Chapter Contents | Next